﻿/****************************************************************************************************
	Copyright (C) 2010 RapidWebDev Organization (http://rapidwebdev.org)
	Author: Eunge, Legal Name: Jian Liu, Email: eunge.liu@RapidWebDev.org

	This program is free software: you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation, either version 2 of the License, or
	(at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program.  If not, see <http://www.gnu.org/licenses/>.
 ****************************************************************************************************/

using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Web.Security;
using System.Security.Principal;

namespace BaoJianSoft.Platform
{
	/// <summary>
	/// RapidWebDev Membership gives you a built-in way to validate and store user credentials which developed on ASP.NET Membership.
	/// The membership therefore helps you manage user authentication in your Web sites. 
	/// With extended from ASP.NET membership, you can configure the membership by ASP.NET Membreship Configuration as seeing the topic "Configuring an ASP.NET Application to Use Membership" in MSDN.
	/// The RapidWebDev membership model is NOT compatible to ASP.NET Membership Controls like Login Control, PasswordRecovery Control.
	/// </summary>
	public interface IMembershipApi
	{
		/// <summary>
		/// Save user object with specified password and password retrieval answer. 
		/// If it's used to update an existed user, the password allows to be null in the case that it doesn't need to change the password of the user.
		/// The argument "passwordAnswer" is to be validated depends on the configuration on ASP.NET Membership "RequiresQuestionAndAnswer".
		/// </summary>
		/// <param name="userObject">user business object</param>
		/// <param name="password">login password. If it's used to update an existed user, the password allows to be null in the case that it doesn't need to change the password of the user.</param>
		/// <param name="passwordAnswer">password retrieve answer. The argument "passwordAnswer" is to be validated depends on the configuration on ASP.NET Membership "RequiresQuestionAndAnswer".</param>
		/// <exception cref="ValidationException">Save user failed by various reasons implied in exception message.</exception>
		/// <exception cref="ArgumentException">The property userObject.Id is specified with an invalid value.</exception>
		/// <exception cref="ArgumentNullException">The argument userObject is null.</exception>
		void Save(UserObject userObject, string password, string passwordAnswer);

		/// <summary>
		/// Resolve user objects from enumerable user ids.
		/// </summary>
		/// <param name="userIds"></param>
		/// <returns></returns>
		IDictionary<Guid, UserObject> BulkGet(IEnumerable<Guid> userIds);

		/// <summary>
		/// Get user by user name.
		/// </summary>
		/// <param name="userName"></param>
		/// <returns></returns>
		UserObject Get(string userName);

		/// <summary>
		/// Get user object by user id.
		/// </summary>
		/// <param name="userId">user id</param>
		/// <returns></returns>
		UserObject Get(Guid userId);

		/// <summary>
		/// Validate user is authenticated to application. 
		/// Either invalid credential or unauthenticated company will lead to login failed.
		/// </summary>
		/// <param name="username">user name</param>
		/// <param name="password">password</param>
		LoginResults Login(string username, string password);

		/// <summary>
		/// Change password of specified user. 
		/// </summary>
		/// <param name="userId"></param>
		/// <param name="oldPassword"></param>
		/// <param name="newPassword"></param>
		/// <returns>returns true if operation successfully.</returns>
		bool ChangePassword(Guid userId, string oldPassword, string newPassword);
	}
}
